Background

experimental_context for tools and step preparation was introduced in an earlier release without typing (type: unknown). Before marking context as stable, it should support smart generic typing for usage in tools, prepareStep, and telemetry.

Summary

Introduce generics on experimental_context. Each tool has a contextSchema for the tool-specific context. The context on the AI function call is a union of the tool contexts and can have additional properties for prepareStep and telemetry.

Limitations

The experimental_context setting is optional even when a context is needed, i.e. it will not throw type validation errors unless a context is specified.

Manual Verification

• run and check types on examples/ai-functions/src/generate-text/openai/tool-call-with-context.ts
• run and check types on examples/ai-functions/src/stream-text/openai/tool-call-with-context.ts
• run and check types on examples/ai-functions/src/agent/openai/generate-context.ts
• run and check types on examples/ai-functions/src/agent/openai/generate-context-call-options.ts

Tasks

• prototype generic context and tool context merging
• investigate type errors
• implement generateText
• implement streamText
• implement agent / tool loop agent
• figure out support in provider-defined tools
• add type tests
• add jsdoc
• update reference documentation
• update context documentation
• update examples in docs that use context
• update migration guide
• remove prototypes
• better name for ExpandedContext
• self-review pr
• changeset

Future Work

• mark experimental_context stable
• add sanitizeContext function
• add tool context wrapper for name mapping and safety
• add context to StopCondition parameters
• move ToolSet into provider-utils package
• investigate how to fix context optionality limitation
• remove ToolCallOptions type